<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<link rel="shortcut icon" type="image/x-icon" href="favicon.ico"/>
<title>DynamoRIO API: Function Wrapping and Replacing Extension</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">DynamoRIO API
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.1.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('page_drwrap.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Function Wrapping and Replacing Extension </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>The <code>drwrap</code> DynamoRIO Extension provides function wrapping and replacing support.</p>
<ul>
<li><a class="el" href="page_drwrap.html#sec_drwrap_setup">Setup</a></li>
<li><a class="el" href="page_drwrap.html#sec_drwrap_events">Event Replacement</a></li>
<li><a class="el" href="page_drwrap.html#sec_drwrap_api">API</a></li>
<li><a class="el" href="page_drwrap.html#sec_drwrap_license">LGPL 2.1 License</a></li>
</ul>
<h1><a class="anchor" id="sec_drwrap_setup"></a>
Setup</h1>
<p>To use <code>drwrap</code> with your client simply include this line in your client's <code>CMakeLists.txt</code> file:</p>
<div class="fragment"><div class="line"> use_DynamoRIO_extension(clientname drwrap) </div>
</div><!-- fragment --><p>That will automatically set up the include path and library dependence.</p>
<p>Initialize and clean up <code>drwrap</code> by calling <a class="el" href="group__drwrap.html#ga23837833101ebc340ac7de6e8340bb4a">drwrap_init()</a> and <a class="el" href="group__drwrap.html#ga0e58babc53301c4ade4027dc1e09a088">drwrap_exit()</a>.</p>
<h1><a class="anchor" id="sec_drwrap_events"></a>
Event Replacement</h1>
<p><code>drwrap</code> uses the <code>drmgr</code> Extension to ensure its events occur at the proper order. A user of <code>drwrap</code> must use the <code>drmgr</code> versions of the basic block and thread events.</p>
<h1><a class="anchor" id="sec_drwrap_api"></a>
API</h1>
<p>The first step in replacing or wrapping is to determine the address of the target application function. For functions exported by an application library, use <a class="el" href="dr__tools_8h.html#a8da7923ecc4e020e31442bcc8d9f8d3e">dr_get_proc_address()</a> to locate the entry point. For internal functions, use the drsyms Extension (see <a class="el" href="page_drsyms.html">Symbol Access Library</a>).</p>
<p>Function replacing is provided by <a class="el" href="group__drwrap.html#ga488a6566cd760a3919bdd2f49a6d672f">drwrap_replace()</a>. The replacement function executes as application code and will be passed to the client via the basic block and trace events just like any other application code. The replaced function may still show up in the basic block event as a jump instruction; none of its actual code will execute. To avoid changing application behavior, ensure that the replacement function mirrors the calling convention and other semantics of the original function.</p>
<p>Function wrapping is provided by <a class="el" href="group__drwrap.html#ga4c004987daae07af15f2146c2d7d4b09">drwrap_wrap()</a>. A pre-function and post-function callback must be provided. The pre-function callback is invoked prior to every execution of the target function. The callback can examine and change function arguments and can skip the call to the target function (in which case there will be no post-function callback). The post-function callback can examine and change the target function's return value. Information (included copies of the arguments for examination in the post-function) can be passed between the pre- and post-functions via a user-controlled parameter.</p>
<p>Multiple wrap requests are allowed for one target function. Their callbacks are called sequentially in the reverse order of registration. If any pre-function callback asks to skip the function, the remaining pre-function callbacks will not be called, nor will any post-function callback.</p>
<h1><a class="anchor" id="sec_drwrap_license"></a>
LGPL 2.1 License</h1>
<p>The <code>drwrap</code> Extension is licensed under the LGPL 2.1 License and NOT the BSD license used for the rest of DynamoRIO. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer" style="float:none;text-align:center"><img border=0 src="favicon.png"> &nbsp;  DynamoRIO API version 5.0.0 --- Wed Sep 10 2014 21:36:44 &nbsp; <img border=0 src="favicon.png">
</small></address>
<!--END !GENERATE_TREEVIEW-->
</body>
</html>
